;*****************************************************************************************************
;+
; NAME:
;
;      ePLOTS (enhanced PLOTS)
;
; PURPOSE:
;
;      This is the enhanced version of the standard IDL PLOTS
;      command. It uses the same syntax and support most of the IDL
;      plotting keywords. The output polygon is displayed in an IGL window
;      so that you can easily interact with it. Note that ePLOTS also
;      provides the capability to fill the polygon with a given color
;      so that you can use it as an enhanced version of POLYFILL.
; 
;
; CALLING SEQUENCE:
;
;      ePLOTS, xpts, ypts
;
; ARGUMENTS:
;
;     XPTS:         A vector providing the X coordinates of the
;                   vertices points to be connected.
;
;     YPTS:         A vector providing the Y coordinates of the
;                   vertices points to be connected. 
;                 
; KEYWORD PARAMETERS:
;
;     BACKGROUND:   Set this keyword to fill the polygon with a given
;                   color specified by BGCOLOR. This is similar to the
;                   POLYFILL procedure.
;
;     BGCOLOR:      The name of the background color when filling the
;                   polygon (BACKGROUND=1). The default is !IGL_P.background
;
;     COLOR:        Either a scalar or a vector of color
;                   specifications. Each color can be either specified
;                   by its name or by an index in the color table. The
;                   default is !IGL_P.color
;
;     DATA:         Set this keyword to indicate that positioning
;                   parameters are given in data coordinates. In this
;                   case, there MUST be a valid coordinate
;                   system. Also note that the polygon is attached to
;                   the coordinate system. This is the default
;                   behaviour.
;
;     DEVICE:       Set this keyword to indicate that positioning
;                   parameters are given in device coordinates. This
;                   also prevents the polygon to be attached to any
;                   coordinate system.
;
;     LINESTYLE:    The style for the polygon line segments (integer). The default
;                   is !IGL_P.linestyle
;
;     NOCLIP:       If set, prevent the clipping at the edge of the
;                   plot window. The default is to clip the polygon
;                   only if the data coordinates are used.
;
;     NODRAW:       *IGL ADDITION* : Set this keyword to prevent the
;                   current window to be refreshed. The polygon
;                   is added to the window but will not be
;                   visible until the window is refreshed (by calling
;                   another IGL plotting command for example). This is
;                   useful is you wish to issue several plotting
;                   commands but want to display the results only at
;                   the end.
;
;     NORMAL:       Set this keyword to indicate that positioning
;                   parameters are given in normalized coordinates. This
;                   also prevents the polygon to be attached to any
;                   coordinate system.
;
;     PSYM:         An integer specifiying the plotting symbol to
;                   use. All the symbols from the SYMCAT
;                   routine (Coyote Library) are directly available. The
;                   default is !IGL_P.psym
;
;     SYMSIZE:      The size of the symbols when PSYM is set
;                   (float). The default is !IGL_P.symsize
;
;     THICK:        The thickness of the line segments (integer). The default
;                   is !IGL_P.thick
;    
; PACKAGE:
;
;    Interactive Graphics Library (IGL)
;
; AUTHORS:
;
;        RAPHAEL SADOUN
;        Graduate Student
;        Institut d'Astrophysique de Paris
;        98 bis boulevard Arago
;        75014 PARIS FRANCE
;        E-mail: raphael.sadoun@gmail.com
;
;
; MODIFICATION HISTORY:
;
;     Written by: Raphael Sadoun, 24 April 2012
;-
;*****************************************************************************************************
PRO ePLOTS, xpts, ypts, $
            BACKGROUND=background, $
            BGCOLOR=bgcolor, $            
            COLOR=color, $
            DATA=data, $
            DEVICE=device, $
            LINESTYLE=linestyle, $
            NOCLIP=noclip, $
            NODRAW=nodraw, $
            NORMAL=normal, $
            PSYM=psym, $
            SYMSIZE=symsize, $
            THICK=thick

  COMPILE_OPT idl2, HIDDEN
  ON_ERROR, 2

  ;; Initialize the global system variables
  IGL_InitSysVars

  ;; Check positional parameters
  IF N_PARAMS() NE 2 THEN Message, 'Polygon coordinates are not specified'
  IF N_Elements(xpts) NE N_Elements(ypts) THEN Message, 'Coordinate vectors must have same number of elements'

  ;; Default keyword values
  IF N_Elements(bgcolor) EQ 0 THEN bgcolor = !IGL_P.background
  IF N_Elements(color) EQ 0 THEN color = !IGL_P.color
  IF N_Elements(linestyle) EQ 0 THEN linestyle = !IGL_P.linestyle
  IF N_Elements(psym) EQ 0 THEN psym = !IGL_P.psym
  IF N_Elements(symsize) EQ 0 THEN symsize = (!IGL_P.symsize LE 0) ? 1 : !IGL_P.symsize
  IF N_Elements(thick) EQ 0 THEN thick = (!IGL_P.thick LE 0) ? 1 : !IGL_P.thick

  ;; Save device settings and switch to window device
  entryDevice = !d.name
  IF (strupcase(!version.os_family) EQ 'UNIX') THEN set_plot, 'X'
  IF (strupcase(!version.os_family) EQ 'WINDOWS') THEN set_plot, 'WIN'

  ;; Get current window
  currentWindow = IGL_GetCurrentWindow()
  IF OBJ_ISA_VALID(currentWindow,'IGL_WINDOW') EQ 0 THEN Message, 'No valid IGL window available'
  currentWindow -> GetProperty, Window_Xsize=Xsize, Window_Ysize=Ysize

  ;; Create the polygon object
  polygon = Obj_New('IGL_Polygon', $
                    XPTS=xpts, $
                    YPTS=ypts, $
                    BACKGROUND=Keyword_Set(background), $
                    BG_COLOR=bgcolor, $
                    PCOLORS=color, $
                    LINESTYLE=linestyle, $
                    CLIP=0, $
                    PSYM=psym, $
                    SYMSIZE=symsize, $
                    THICK=thick $
                   )

  ;; Create a coordinate system for the polygon
  
  IF Keyword_Set(device) THEN BEGIN ; Device coordinate system
     
     coords = Obj_New('IGL_Coord', $
                      POSITION=[0,0,1,1], $
                      XRANGE=[0,Xsize], $
                      YRANGE=[0,Ysize] $
                     )

     polygon -> SetProperty, Coord_Object=coords
     currentWindow -> AddGraphic, polygon
     
  ENDIF

  IF Keyword_Set(normal) THEN BEGIN ; Normalized coordinate system

     coords = Obj_New('IGL_Coord', $
                      POSITION=[0,0,1,1], $
                      XRANGE=[0,1], $
                      YRANGE=[0,1] $
                     )

     polygon -> SetProperty, Coord_Object=coords
     currentWindow -> AddGraphic, polygon
     
  ENDIF

  IF Keyword_Set(data) OR (N_Elements(coords) EQ 0) THEN BEGIN ; Data coordinate system

     ;; Get the current coordinate system
     currentCoords = IGL_GetSysVars('currentCoord')
     IF OBJ_ISA_VALID(currentCoords,'CatCoord') EQ 0 THEN Message, 'A coordinate system is not established'
     
     ;; Get the object that represents the coordinate system in the graphic
     currentCoords -> GetProperty, FIRST_PARENT=parent
     IF OBJ_VALID(parent) EQ 0 THEN Message, 'Invalid coordinate system'
     
     ;; Get the graphic in which the parent object is contained
     parent -> GetProperty, FIRST_PARENT=graphic
     IF OBJ_ISA_VALID(graphic,'IGL_Graphic') EQ 0 THEN message, 'Current coordinate system is not in a valid graphic'

     ;; Set polygon's properties
     polygon -> SetProperty, Coord_Object=currentCoords, Selectable=0, Clip=1

     ;; Add the polygon to the coordinate system's owner
     parent -> Add, polygon

  ENDIF

  ;; Refresh the property editor
  currentWindow -> GetProperty, PropertyPanel=PropertyPanel
  IF OBJ_VALID(PropertyPanel) THEN PropertyPanel -> UpdateTreeBrowser
  
  ;; Draw window's content
  IF Keyword_set(nodraw) EQ 0 THEN currentWindow -> DrawWindow, /Buffered_Output 

END
